Web API の設計
原著 : The Design of Web APIs
著 : Arnaud Lauret
翻訳 / 監修 : 株式会社クイープ
発行年 : 2020 年
https://m.media-amazon.com/images/I/61GK-dw0hDL._SX260_.jpg
Amazon : https://amzn.to/3Y3i7av
本書に寄せて (Kin Lane)
過去 10 年以上、API 設計とは、ほとんどの開発者にとって REST のことだった
本書は、次世代の API ガイダンスの第一波
本書は、API 設計と OpenAPI (以前は Swagger) を考え抜かれた実践的な方法で融合させた初めての API 設計の本
1 部 API デザインの基礎
1 章 API デザインとは何か
Web API は、現代の 「つながる世界」 の大黒柱とも言えるもの
リモート API、その中でも特に Web API によって、ソフトウェアを作る方法に大変革が起きている
2 章 ユーザーを意識した API を設計する
API を設計するにあたって、包括的で正確なゴールリストを作る
ユーザーは誰か？ (例えば管理者もユーザーになる)
ユーザーの目標 (ゴール) に対して、「何を」 「どのように」 実現するかを考える
さらに、それぞれのステップにおける 「入力」 と 「出力」 を考える
入力はどこから得る？ 出力はどう使われる？ ということを考えると、見落としている API のゴールを洗い出せる
上記のゴールリストを作るにあたって、API のゴールキャンバスを活用する
API 設計にプロバイダの視点を入れないようにする
API 設計にも Conway の法則は影響しうる (API 設計は、API を提供している組織のコミュニケーション構造を反映しうる)
内部のデータ構造を露出しないように
ビジネスロジックや複数のシステムが連携する場合のアーキテクチャなどの影響も受けないように
組織構造の影響を受けないように
3 章 プログラミングインターフェイスを設計する
REST、HTTP、REST API
REST という API スタイル以上に、REST アーキテクチャスタイルという土台が大事
4 章 API 記述フォーマットを使って API を記述する
OpenAPI Specification (OAS) はよく知られている REST API 記述フォーマット
2 部 ユーザブルな API の設計
API にはユーザビリティも重要
5 章 単純明快な API を設計する
単純明快な表現 : 明確な名前、使いやすいデータ型とデータフォーマット
単純明快なインタラクション
エラーフィードバックを洗い出す
不正な形式のリクエストエラー (malformed request error)
機能的エラー (functional error)
サーバーエラー
情報的価値のある成功およびエラーのフィードバック
包括的なエラーフィードバック : エラーが複数あるならばまとめてエラーを返す
単純明快なフロー
6 章 予測可能な API を設計する
4 つのレベルの一貫性 : API 内部、組織・企業・チームの API にまたがる一貫性、API の問題領域での一貫性、外の世界との一貫性
標準に従う
例
「再生」 と 「一時停止」 の記号は ISO 7000 で定義されている
通貨の分類は ISO 4217
日付と時刻は ISO 8601
HTTP の標準に従うという意味でも
適応可能な API
さまざまなフォーマット
JSON、CSV、PDF などの様々なフォーマット
コンテンツネゴシエーションを使える
国際化と地域化
ISO 639 に言語コードが規定されているが、アメリカ英語とイギリス英語の違いなどはない
RFC 5646 では言語タグが定義されている (ISO 639 の言語コードと、ISO 3166 の国コードを採用)
HTTP では Accept-Language と Content-Language
フィルタリング、ページング、ソート
発見可能性
メタデータの提供
ハイパーメディア API
ハイパーメディアフォーマット
HAL、Collection+JSON、JSON API、JSON-LD、Hydra、Siren など
7 章 うまく整理された簡潔な API を設計する
3 部 コンテキストに応じた API デザイン
セキュア・バイ・デザイン (secure by design) である必要
API の互換性
ネットワークの制約
など
8 章 セキュアな API を設計する
『OAuth 2 in Action』 や 『API Security in Action』 が詳しい
RFC 6749 の OAuth 2.0 の認可フレームワークを紹介 (これが唯一の選択肢ではないがよく利用される)
OWASP (Open Web Application Security Project)
最小権限の原則
エンドポイントをスコープで分類して、スコープごとのアクセス制御を行う
OpenAPI Specification 3.0 はスコープをサポートする
センシティブなデータの扱いにも気を付ける
法規制などもある
銀行のクレジット / デビットカードの扱い : PCI DSS (Payment Card Industry Data Security Standard)
アメリカのヘルスケアプロバイダの規制 : HIPAA (Health Insurance Portability and Accountability Regulation)
EU の GDPR (General Data Protection Regulation)
9 章 API の設計を進化させる
破壊的変更 (互換性のない変更) に注意
API のバージョニング
セマンティックバージョニング
拡張可能性
10 章 ネットワーク効率のよい API を設計する
ネットワークの通信効率は重要
HTTP API におけるネットワーク通信の最適化
GraphQL
API をレイヤ化する
Backend For Frontend (BFF)
エクスペリエンス API
11 章 コンテキストに基づいて API を設計する
設計はコンテキストの影響を受ける (人々が何に慣れているのか、など)
QWERTY の話
ISO 20022 規格
ポーリングではなくコンシューマにイベントを通知
Web フック (リバース API)
Server-Sent Events (SSE)
WebSocket
HTTP 207 Multi-Status
道具の法則 (ハンマーの法則やマズローの法則とも) と呼ばれる認知バイアス
Web API の基本である同期型のリクエスト / レスポンス + REST + HTTP/1.1 + JSON を常に使いたくなるかもしれない
他の選択肢もある
REST、gRPC、GraphQL
データフォーマットとして、protocol buffers も
同期型のリクエスト / レスポンスだけでなく、イベント通知も
Web フック、WebSub
RabbitMQ などのメッセージングシステム
信頼性の低いネットワークやスリーピングデイバス (nobuoka.icon スリーピングデバイスの誤植？) を使った双方向通信には MQTP (Message Queuing Telemetry Protocol)
大量のイベントフローの処理には Kafka Streams など
12 章 API を文書化する
利用者向けの説明書だけでなく、実装者向けの説明書も必要 (あるいは設計者が実装に参加する)
Redoc
13 章 API を成長させる
API の設計ガイドライン
Web Concepts
標準化されている規格が多いが、全部を知っている事は難しい
例えば電話番号については ITU-T E.164
判断力と検索エンジンの力が重要
#書籍 #文献